<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Apache Tomcat 4 - JNDI Datasource HOW-TO</title><meta name="author" value="Les Hughes"><meta name="email" value="leslie.hughes@rubus.com"><meta name="author" value="David Haraburda"><meta name="email" value="david-tomcat@haraburda.com"><meta name="author" value="Glenn Nielsen"><meta name="email" value=""></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./../images/tomcat.gif" align="right" alt="
      The Tomcat Servlet/JSP Container
    " border="0"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 4</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top" nowrap="true"><h1>JNDI Datasource HOW-TO</h1></td><td align="right" valign="top" nowrap="true"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<p>
<a href="#Introduction">Introduction</a><br>
<a href="#Database Connection Pool (DBCP) Configurations">
Database Connection Pool (DBCP) Configurations</a><br>
<a href="#Tyrex Connection Pool">Tyrex Connection Pool</a><br>
<a href="#Non DBCP Solutions">Non DBCP Solutions</a><br>
<a href="#Oracle 8i with OCI client">Oracle 8i with OCI client</a><br>
<a href="#Common Problems">Common Problems</a><br>
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

<p>JNDI Datasource configuration is covered extensively in the
JNDI-Resources-HOWTO however, feedback from <code>tomcat-user</code> has
shown that specifics for individual configurations can be rather tricky.</p>

<p>Here then are some example configurations that have been posted to
tomcat-user for popular databases and some general tips for db useage.</p>

<p>You should be aware that since these notes are derived from configuration
and/or feedback posted to <code>tomcat-user</code> YMMV :-). Please let us
know if you have any other tested configurations that you feel may be of use
to the wider audience, or if you feel we can improve this section in anyway.</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Database Connection Pool (DBCP) Configurations"><strong>Database Connection Pool (DBCP) Configurations</strong></a></font></td></tr><tr><td><blockquote>

<p>DBCP provides support for JDBC 2.0.  On systems using a 1.4 JVM DBCP
will support JDBC 3.0. Please let us know if you have used DBCP and its
JDBC 3.0 features with a 1.4 JVM.
</p>

<p>See the <a href="http://jakarta.apache.org/commons/dbcp/api/index.html">
DBCP Javadocs</a> BasicDataSource class for a complete list
of configuration parameters.
</p>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
<p>DBCP uses the Jakarta-Commons Database Connection Pool. It relies on
number of Jakarta-Commons componenets:
<ul>
<li>Jakarta-Commons DBCP 1.0</li>
<li>Jakarta-Commons Collections 2.0</li>
<li>Jakarta-Commons Pool 1.0</li>
</ul>
These jar files along with your the jar file for your JDBC driver should
be installed in <code>$CATALINA_HOME/common/lib</code>.
<blockquote>
<strong>NOTE:</strong>Third Party drivers should be in jarfiles, not zipfiles.
Tomcat only adds <code>$CATALINA_HOME/common/lib/*.jar</code> to the classpath.
</blockquote>
<blockquote>
<strong>NOTE:</strong>
Do not install these jarfiles in your <code>/WEB-INF/lib</code>, or
<code>$JAVA_HOME/jre/lib/ext</code>, or anywhere else.  You will
experience problems if you install them anyplace other than
<code>$CATALINA_HOME/common/lib</code>.
</blockquote>
</p>

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Preventing dB connection pool leaks"><strong>Preventing dB connection pool leaks</strong></a></font></td></tr><tr><td><blockquote>

<p>
A database connection pool creates and manages a pool of connections
to a database. Recycling and reusing already existing connections
to a dB is more efficient than opening a new connection.
</p>

<p>
There is one problem with connection pooling.  A web application has
to explicetely close ResultSet's, Statement's, and Connection's.
Failure of a web application to close these resources can result in
them never being available again for reuse, a db connection pool "leak".
This can eventually result in your web application db connections failing
if there are no more available connections.</p>

<p>
There is a solution to this problem.  The Jakarta-Commons DBCP can be
configured to track and recover these abandoned dB connections.  Not
only can it recover them, but also generate a stack trace for the code
which opened these resources and never closed them.</p>

<p>
To configure a DBCP DataSource so that abandoned dB connections are
removed and recycled add the following <code>paramater</code> to the
<code>ResourceParams</code> configuration for your DBCP DataSource
<code>Resource</code>:
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
            &lt;parameter&gt;
              &lt;name&gt;removeAbandoned&lt;/name&gt;
              &lt;value&gt;true&lt;/value&gt;
            &lt;/parameter&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
When available db connections run low DBCP will recover and recyle
any abandoned dB connections it finds. The default is <code>false</code>.
</p>

<p>
Use the <code>removeAbandonedTimeout</code> parameter to set the number
of seconds a dB connection has been idle before it is considered abandoned.
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
            &lt;parameter&gt;
              &lt;name&gt;removeAbandonedTimeout&lt;/name&gt;
              &lt;value&gt;60&lt;/value&gt;
            &lt;/parameter&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
The default timeout for removing abandoned connections is 300 seconds.
</p>

<p>
The <code>logAbandoned</code> parameter can be set to <code>true</code>
if you want DBCP to log a stack trace of the code which abandoned the
dB connection resources.
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
            &lt;parameter&gt;
              &lt;name&gt;logAbandoned&lt;/name&gt;
              &lt;value&gt;true&lt;/value&gt;
            &lt;/parameter&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
The default is <code>false</code>.
</p>

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="MySQL DBCP Example"><strong>MySQL DBCP Example</strong></a></font></td></tr><tr><td><blockquote>

<h3>0. Introduction</h3>
<p>Versions of MySQL and the mm.mysql JDBC driver when have been
reported to work:
<ul>
<li>MySQL 3.23.47, MySQL 3.23.47 using InnoDB, MySQL 4.0.1alpha</li>
<li>mm.mysql 2.0.14 (JDBC Driver)</li>
</ul>
Please let us know if you have tested the new MySQL mm.mysql 3.0 driver.
</p>

<h3>1. MySQL configuration</h3>
<p>
Ensure that you follow these instructions as variations can cause problems.
</p>

<p>Create a new test user, a new database and a single test table.
Your MySQL user <strong>must</strong> have a password assigned. The driver
will fail if you try to connect with an empty password.
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
mysql&gt; GRANT ALL PRIVILEGES ON *.* TO javauser@localhost 
    -&gt;   IDENTIFIED BY 'javadude' WITH GRANT OPTION;
mysql&gt; create database javatest;
mysql&gt; use javatest;
mysql&gt; create table testdata (
    -&gt;   id int not null auto_increment primary key,
    -&gt;   foo varchar(25), 
    -&gt;   bar int);
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<blockquote>
<strong>Note:</strong> the above user should be removed once testing is
complete!
</blockquote>
</p>

<p>Next insert some test data into the testdata table.
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
mysql&gt; insert into testdata values(null, 'hello', 12345);
Query OK, 1 row affected (0.00 sec)

mysql&gt; select * from testdata;
+----+-------+-------+
| ID | FOO   | BAR   |
+----+-------+-------+
|  1 | hello | 12345 |
+----+-------+-------+
1 row in set (0.00 sec)

mysql&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</p>

<h3>2. server.xml configuration</h3>
<p>Configure the JNDI DataSource in Tomcat by adding a declaration for your
resource to <code>$CATALINA_HOME/conf/server.xml</code>.</p>
<p>Add this in between the <code>&lt;/Context&gt;</code> tag of the examples
context and the <code>&lt;/Host&gt;</code> tag closing the localhost definition.<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Context path="/DBTest" docBase="DBTest"
        debug="5" reloadable="true" crossContext="true"&gt;

  &lt;Logger className="org.apache.catalina.logger.FileLogger"
             prefix="localhost_DBTest_log." suffix=".txt"
             timestamp="true"/&gt;

  &lt;Resource name="jdbc/TestDB"
               auth="Container"
               type="javax.sql.DataSource"/&gt;

  &lt;ResourceParams name="jdbc/TestDB"&gt;
    &lt;parameter&gt;
      &lt;name&gt;factory&lt;/name&gt;
      &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;!-- Maximum number of dB connections in pool. Make sure you
         configure your mysqld max_connections large enough to handle
         all of your db connections. Set to -1 for no limit.
         --&gt;
    &lt;parameter&gt;
      &lt;name&gt;maxActive&lt;/name&gt;
      &lt;value&gt;100&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;!-- Maximum number of idle dB connections to retain in pool.
         Set to 0 for no limit.
         --&gt;
    &lt;parameter&gt;
      &lt;name&gt;maxIdle&lt;/name&gt;
      &lt;value&gt;30&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;!-- Maximum time to wait for a dB connection to become available
         in ms, in this example 10 seconds. An Exception is thrown if
         this timeout is exceeded.  Set to -1 to wait indefinitely.
         --&gt;
    &lt;parameter&gt;
      &lt;name&gt;maxWait&lt;/name&gt;
      &lt;value&gt;10000&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;!-- MySQL dB username and password for dB connections  --&gt;
    &lt;parameter&gt;
     &lt;name&gt;username&lt;/name&gt;
     &lt;value&gt;javauser&lt;/value&gt;
    &lt;/parameter&gt;
    &lt;parameter&gt;
     &lt;name&gt;password&lt;/name&gt;
     &lt;value&gt;javadude&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;!-- Class name for mm.mysql JDBC driver --&gt;
    &lt;parameter&gt;
       &lt;name&gt;driverClassName&lt;/name&gt;
       &lt;value&gt;org.gjt.mm.mysql.Driver&lt;/value&gt;
    &lt;/parameter&gt;

    &lt;!-- The JDBC connection url for connecting to your MySQL dB.
         --&gt;
    &lt;parameter&gt;
      &lt;name&gt;url&lt;/name&gt;
      &lt;value&gt;jdbc:mysql://localhost:3306/javatest&lt;/value&gt;
    &lt;/parameter&gt;
  &lt;/ResourceParams&gt;
&lt;/Context&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</p>

<h3>3. web.xml configuration</h3>

<p>Now create a <code>WEB-INF/web.xml</code> for this test application.
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
    &lt;!DOCTYPE web-app PUBLIC
    "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd"&gt;
&lt;web-app&gt;
  &lt;description&gt;MySQL Test App&lt;/description&gt;
  &lt;resource-ref&gt;
      &lt;description&gt;DB Connection&lt;/description&gt;
      &lt;res-ref-name&gt;jdbc/TestDB&lt;/res-ref-name&gt;
      &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
      &lt;res-auth&gt;Container&lt;/res-auth&gt;
  &lt;/resource-ref&gt;
&lt;/web-app&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</p>

<h3>4. Test code</h3>
<p>Now create a simple test.jsp for use later.
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;DB Test&lt;/title&gt;
  &lt;/head&gt;
  &lt;body&gt;

  &lt;%
    foo.DBTest tst = new foo.DBTest();
    tst.init();
  %&gt;

  &lt;h2&gt;Results&lt;/h2&gt;
    Foo &lt;%= tst.getFoo() %&gt;&lt;br/&gt;
    Bar &lt;%= tst.getBar() %&gt;

  &lt;/body&gt;
&lt;/html&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</p>

<p>And create a Java class to actually use your new Datasource and connection
pool. Note: this code isn't anywhere near production ready - it's only
supposed to be used as a simple test :-)
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
package foo;

import javax.naming.*;
import javax.sql.*;
import java.sql.*;

public class DBTest {

  String foo = "Not Connected";
  int bar = -1;
    
  public void init() {
    try{
      Context ctx = new InitialContext();
      if(ctx == null ) 
          throw new Exception("Boom - No Context");

      DataSource ds = 
            (DataSource)ctx.lookup(
               "java:comp/env/jdbc/TestDB");

      if (ds != null) {
        Connection conn = ds.getConnection();
              
        if(conn != null)  {
            foo = "Got Connection "+conn.toString();
            Statement stmt = conn.createStatement();
            ResultSet rst = 
                stmt.executeQuery(
                  "select id, foo, bar from testdata");
            if(rst.next()) {
               foo=rst.getString(2);
               bar=rst.getInt(3);
            }
            conn.close();
        }
      }
    }catch(Exception e) {
      e.printStackTrace();
    }
 }

 public String getFoo() { return foo; }
 public int getBar() { return bar;}
}
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</p>

<p>Finally deploy your web app into <code>$CATALINA_HOME/webapps</code> either
as a warfile called <code>DBTest.war</code> or into a sub-directory called
<code>DBTest</code></p>
<p>Once deployed, point a browser at
<code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of
your hard work.</p>

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Oracle 8i, 9i &amp; 10g"><strong>Oracle 8i, 9i &amp; 10g</strong></a></font></td></tr><tr><td><blockquote>
<h3>0.    Introduction</h3>

<p>Oracle requires minimal changes from the MySQL configuration except for the
usual gotchas :-)</p>
<p>Drivers for older Oracle versions may be distributed as *.zip files rather
than *.jar files. Tomcat will only use <code>*.jar</code> files installed in
<code>$CATALINA_HOME/common/lib</code>. Therefore <code>classes111.zip</code>
or <code>classes12.zip</code> will need to be renamed with a <code>.jar</code>
extension. Since jarfiles are zipfiles, there is no need to unzip and jar these
files - a simple rename will suffice.</p>

<p>Some early versions of Tomcat 4.0 when used with JDK 1.4 will not load
classes12.zip unless you unzip the file, remove the <code>javax.sql.*</code>
class heirarchy and rejar.</p>

<p>For Oracle 9i onwards you should use <code>oracle.jdbc.OracleDriver</code>
rather than <code>oracle.jdbc.driver.OracleDriver</code> as Oracle have stated
that <code>oracle.jdbc.driver.OracleDriver</code> is deprecated and support
for this driver class will be discontinued in the next major release.
</p>

<h3>1.    server.xml configuration</h3>
<p>In a similar manner to the mysql config above, you will need to define your
Datasource in your server.xml file. Here we define a Datasource called myoracle
using the thin driver to connect as user scott, password tiger to the sid
called mysid. (Note: with the thin driver this sid is not the same as the
tnsname). The schema used will be the default schema for the user scott.</p>

<p>Use of the OCI driver should simply involve a changing thin to oci in the URL
string.
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Resource name="jdbc/myoracle" auth="Container"
              type="javax.sql.DataSource"/&gt; 

&lt;ResourceParams name="jdbc/myoracle"&gt;
  &lt;parameter&gt;
    &lt;name&gt;factory&lt;/name&gt;
    &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;driverClassName&lt;/name&gt;
    &lt;value&gt;oracle.jdbc.OracleDriver&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;url&lt;/name&gt;
    &lt;value&gt;jdbc:oracle:thin:@127.0.0.1:1521:mysid&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;username&lt;/name&gt;
    &lt;value&gt;scott&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;password&lt;/name&gt;
    &lt;value&gt;tiger&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;maxActive&lt;/name&gt;
    &lt;value&gt;20&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;maxIdle&lt;/name&gt;
    &lt;value&gt;10&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;maxWait&lt;/name&gt;
    &lt;value&gt;-1&lt;/value&gt;
  &lt;/parameter&gt;
&lt;/ResourceParams&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</p>

<h3>2.    web.xml configuration</h3>
<p>You should ensure that you respect the elemeent ordering defined by the DTD when you
create you applications web.xml file.</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;resource-ref&gt;
 &lt;description&gt;Oracle Datasource example&lt;/description&gt;
 &lt;res-ref-name&gt;jdbc/myoracle&lt;/res-ref-name&gt;
 &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
 &lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<h3>3.   Code example</h3>
<p>You can use the same example application as above (asuming you create the required DB
instance, tables etc.) replacing the Datasource code with something like</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
Context initContext = new InitialContext();
Context envContext  = (Context)initContext.lookup("java:/comp/env");
DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle");
Connection conn = ds.getConnection();
//etc.
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</blockquote></td></tr></table>


<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="PostgreSQL"><strong>PostgreSQL</strong></a></font></td></tr><tr><td><blockquote>
<h3>0.    Introduction</h3>
<p>PostgreSQL is configured in a similar manner to Oracle. Again, highlighting the differences.
These notes are untested as yet and we would appreciate feedback.</p>
<h3>1.    server.xml configuration</h3>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Resource name="jdbc/postgres" auth="Container"
          type="javax.sql.DataSource"/&gt; 

&lt;ResourceParams name="jdbc/postgres"&gt;
  &lt;parameter&gt;
    &lt;name&gt;factory&lt;/name&gt;
    &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;driverClassName&lt;/name&gt;
    &lt;value&gt;org.postgresql.Driver&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;url&lt;/name&gt;
    &lt;value&gt;jdbc:postgresql://127.0.0.1:5432/mydb&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;username&lt;/name&gt;
    &lt;value&gt;myuser&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;password&lt;/name&gt;
    &lt;value&gt;mypasswd&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;maxActive&lt;/name&gt;
    &lt;value&gt;20&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;maxIdle&lt;/name&gt;
    &lt;value&gt;10&lt;/value&gt;
  &lt;/parameter&gt;
  &lt;parameter&gt;
    &lt;name&gt;maxWait&lt;/name&gt;
    &lt;value&gt;-1&lt;/value&gt;
  &lt;/parameter&gt;
&lt;/ResourceParams&gt; 
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<h3>2.    web.xml configuration</h3>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;resource-ref&gt;
 &lt;description&gt;postgreSQL Datasource example&lt;/description&gt;
 &lt;res-ref-name&gt;jdbc/mydb&lt;/res-ref-name&gt;
 &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
 &lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</blockquote></td></tr></table>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Tyrex Connection Pool"><strong>Tyrex Connection Pool</strong></a></font></td></tr><tr><td><blockquote>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

<p>
Tomcat 4.1 provides transaction management and resource configuration support through the use of 
<a href="http://tyrex.exolab.org/">Tyrex</a> 1.0. This allows the user to obtain JTA/JCA resources
from the JNDI namespace, as well as the standard <code>javax.transaction.UserTransaction</code>.
</p>

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installing Required JARs"><strong>Installing Required JARs</strong></a></font></td></tr><tr><td><blockquote>

<p>
In order for a web application to use Tyrex, the webapp and Tomcat need to have access to the 
Tyrex jar, as well as the jars it requires.  Here is a list of the required jars, and where to obtain them:
</p>
<p>
The following jars are included with Tyrex binary distribution, available at http://tyrex.exolab.org.

<ul>
<li>tyrex-1.0.jar</li>
<li>ots-jts_1.0.jar</li>
<li>jta_1.0.1.jar</li>
<li>xerces-J_1.4.0.jar</li>
</ul>

The following two jars are required as well:

<ul>
<li>Castor XML jar (<a href="http://castor.exolab.org/">http://castor.exolab.org/</a>, version 0.92 or higher is reccommended)</li>
<li>Log4J (<a href="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j/</a>, version 1.0.4 or higher is reccommended)</li>
</ul>
</p>
<p>
All six of these jar files need to be placed on $TOMCAT_HOME/common/lib so that both Tomcat and your web application will see them.
</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Configuring Tyrex"><strong>Configuring Tyrex</strong></a></font></td></tr><tr><td><blockquote>

<p>
The Tyrex documentation (http://tyrex.exolab.org) provides complete details on how to properly configure Tyrex.  As an example, we will use the following Tyrex configuration, specified in Tyrex's domain configuration XML file:
</p>

<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;domain&gt;
  &lt;name&gt;myDomain&lt;/name&gt;
  &lt;resources&gt;
    &lt;dataSource&gt;
      &lt;name&gt;myDatasource&lt;/name&gt;
      &lt;jar&gt;/home/david/mm.mysql-2.0.14-bin.jar&lt;/jar&gt;
      &lt;class&gt;org.gjt.mm.mysql.jdbc2.optional.MysqlXaDataSource&lt;/class&gt;
      &lt;config&gt;
        &lt;user&gt;david&lt;/user&gt;
        &lt;password&gt;secret&lt;/password&gt;
        &lt;serverName&gt;localhost&lt;/serverName&gt;
        &lt;port&gt;3306&lt;/port&gt;
        &lt;database&gt;daviddb&lt;/database&gt;
      &lt;/config&gt;
    &lt;/dataSource&gt;
  &lt;/resources&gt;
&lt;/domain&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>

<p>
A few things to note:

<ul>
<li>You need to specify the full pathname of the JAR file (for relative paths,  Tyrex looks in the current working directory, this usually isn't what you want).  You can also specify a URL.</li>
<li>Any elements nested inside the <config></config> elements are passed as parameters to the datasource class, using standard setter methods.</li>
<li>More configuration options are available, as well as a better description of how to setup Tyrex, at <a href="http://tyrex.exolab.org/configuration.html">http://tyrex.exolab.org/configuration.html</a></li>
</ul>
</p>
<p>
This XML config file needs to be placed where Tomcat's classloader can find it using getResource().  This means that the WEB-INF/classes directory under your webapp is a very good choice.
</p>
</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Configuring Tomcat"><strong>Configuring Tomcat</strong></a></font></td></tr><tr><td><blockquote>

<p>
Now that your Tyrex XML config file is in place and ready, you must enlist the Tyrex resources in the JNDI namespace.  This is done through Tomcat's server.xml file. 
Two important parameters must be specified: the name of the domain config file (<code>tyrexDomainConfig</code>), and the name of the Tyrex domain that is to be used (<code>tyrexDomainName</code>). 
These need to be setup as Environment parameters, like so:
</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Environment name="tyrexDomainConfig" type="java.lang.String" value="domain-config.xml"/&gt;
&lt;Environment name="tyrexDomainName" type="java.lang.String" value="myDomain"/&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>
Now, you must configure the resource (under the &lt;Context&gt; element of your webapp):
</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Resource name="my-datasource" auth="Container" type="tyrex.resource.Resource"/&gt;
&lt;ResourceParams name="my-datasource"&gt;
  &lt;parameter&gt;
    &lt;name&gt;name&lt;/name&gt;
    &lt;value&gt;myDataSource&lt;/value&gt;
  &lt;/parameter&gt;
&lt;/ResourceParams&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>
A couple of things to point out:
<ul>
<li>The type of resource should always be <code>tyrex.resource.Resource</code>, regardless of how you have Tyrex configured.</li>
<li>Only one ResourceParam parameter is needed, <code>name</code> -- the value should be set to the name of resource specified in the Tyrex config file.</li>
<li>Note the difference between a Tomcat/JNDI resource and a Tyrex resource (it can be confusing at first glance!)</li>
</ul>
</p>
</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Coding Your Application"><strong>Coding Your Application</strong></a></font></td></tr><tr><td><blockquote>

<p>
Making use of your Tyrex resource should now be relatively simple.  To obtain your datasource, simply use JNDI:
</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
InitialContext initCtx = new InitialContext();
DataSource ds = (DataSource) initCtx.lookup("java:comp/env/my-datasource");
Connection conn = ds.getConnection();
...and so on.
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>
Tyrex also provides a <code>javax.transaction.UserTransaction</code>,
 obtainable through JNDI at the standard location (<code>java:comp/UserTransaction</code>).
</p>
</blockquote></td></tr></table>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Non DBCP Solutions"><strong>Non DBCP Solutions</strong></a></font></td></tr><tr><td><blockquote>
<p>
These solutions either utilise a single connection to the database (not recommended for anything other
than testing!) or some other pooling technology.
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Oracle 8i with OCI client"><strong>Oracle 8i with OCI client</strong></a></font></td></tr><tr><td><blockquote>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
<p>Whilst not strictly addressing the creation of a JNDI DataSource using the OCI client, these notes can be combined with the
Oracle and DBCP solution above.</p>
<p>
In order to use OCI driver, you should have an Oracle client installed. You should have installed
Oracle8i(8.1.7) client from cd,  and download the suitable JDBC/OCI
driver(Oracle8i 8.1.7.1 JDBC/OCI Driver) from <a href="http://otn.oracle.com/">otn.oracle.com</a>. 
</p>
<p>
After renaming <code>classes12.zip</code> file to <code>classes12.jar</code>
for Tomcat, copy it into <code>$CATALINA_HOME/common/lib</code>. 
You may also have to remove the <code>javax.sql.*</code> classes
from this file depending upon the version of Tomcat and JDK you are using.
</p>
</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Putting it all together"><strong>Putting it all together</strong></a></font></td></tr><tr><td><blockquote>
<p>
Ensure that you have the <code>ocijdbc8.dll</code> or <code>.so</code> in your <code>$PATH</code> or <code>LD_LIBRARY_PATH</code>
 (possibly in <code>$ORAHOME\bin</code>) and also confirm that the native library can be loaded by a simple test program 
using <code>System.loadLibrary("ocijdbc8");</code>
</p>
<p>
You should next create a simple test servlet or jsp that has these
<strong>critical lines</strong>:
</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
DriverManager.registerDriver(new
oracle.jdbc.driver.OracleDriver());
conn =
DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>
where database is of the form <code>host:port:SID</code> Now if you try to access the URL of your 
test servlet/jsp and what you get is a 
<code>ServletException</code> with a root cause of <code>java.lang.UnsatisfiedLinkError:get_env_handle</code>.
</p>
<p>
First, the <code>UnsatisfiedLinkError</code> indicates that you have 
<ul>
<li>a mismatch between your JDBC classes file and
your Oracle client version. The giveaway here is the message stating that a needed library file cannot be
found. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with a Version 8.1.5
Oracle client. The classeXXXs.zip file and Oracle client software versions must match.
</li>
<li>A <code>$PATH</code>, <code>LD_LIBRARY_PATH</code> problem.</li>
<li>It has been reported that ignoring the driver you have downloded from otn and using 
the classes12.zip file from the directory <code>$ORAHOME\jdbc\lib</code> will also work.
</li>
</ul>
</p>
<p>
Next you may experience the error <code>ORA-06401 NETCMN: invalid driver designator</code>
</p>
<p>
The Oracle documentation says : "Cause: The login (connect) string contains an invalid
driver designator. Action: Correct the string and re-submit."

Change the database connect string (of the form <code>host:port:SID</code>) with this one:
<code>(description=(address=(host=myhost)(protocol=tcp)(port=1521))(connect_data=(sid=orcl)))</code>
</p>
<p>
<i>Ed. Hmm, I don't think this is really needed if you sort out your TNSNames - but I'm not an Oracle DBA :-)</i>
</p>
</blockquote></td></tr></table>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Problems"><strong>Common Problems</strong></a></font></td></tr><tr><td><blockquote>
<p>Here are some common problems encountered with a web application which
uses a database and tips for how to solve them.</p>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Intermittent dB Connection Failures"><strong>Intermittent dB Connection Failures</strong></a></font></td></tr><tr><td><blockquote>
<p>
Tomcat runs within a JVM.  The JVM periodically performs garbage collection
(GC) to remove java objects which are no longer being used.  When the JVM
performs GC execution of code within Tomcat freezes. If the maximum time
configured for establishment of a dB connection is less than the amount
of time garbage collection took you can get a db conneciton failure.
</p>

<p>To collect data on how long garbage collection is taking add the
<code>-verbose:gc</code> argument to your <code>CATALINA_OPTS</code>
environment variable when starting Tomcat.  When verbose gc is enabled
your <code>$CATALINA_BASE/logs/catalina.out</code> log file will include
data for every garbage collection including how long it took.</p>

<p>When your JVM is tuned correctly 99% of the time a GC will take less
than one second.  The remainder will only take a few seconds.  Rarely,
if ever should a GC take more than 10 seconds.</p>

<p>Make sure that the db connection timeout is set to 10-15 seconds.
For the DBCP you set this using the parameter <code>maxWait</code>.</p>

</blockquote></td></tr></table>

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Random Connection Closed Exceptions"><strong>Random Connection Closed Exceptions</strong></a></font></td></tr><tr><td><blockquote>
<p>
These can occur when one request gets a db connection from the connection
pool and closes it twice.  When using a connection pool, closing the
connection just returns it to the pool for reuse by another request,
it doesn't close the connection.  And Tomcat uses multiple threads to
handle concurrent requests. Here is an example of the sequence
of events which could cause this error in Tomcat:
<pre>
  Request 1 running in Thread 1 gets a db connection.

  Request 1 closes the db connection.

  The JVM switches the running thread to Thread 2

  Request 2 running in Thread 2 gets a db connection
  (the same db connection just closed by Request 1).

  The JVM switches the running thread back to Thread 1

  Request 1 closes the db connection a second time in a finally block.

  The JVM switches the running thread back to Thread 2

  Request 2 Thread 2 tries to use the db connection but fails
  because Request 1 closed it.
</pre>
Here is an example of properly written code to use a db connection
obtained from a connection pool:
<pre>
  Connection conn = null;
  Statement stmt = null;  // Or PreparedStatement if needed
  ResultSet rs = null;
  try {
    conn = ... get connection from connection pool ...
    stmt = conn.createStatement("select ...");
    rs = stmt.executeQuery();
    ... iterate through the result set ...
    rs.close();
    rs = null;
    stmt.close();
    stmt = null;
    conn.close(); // Return to connection pool
    conn = null;  // Make sure we don't close it twice
  } catch (SQLException e) {
    ... deal with errors ...
  } finally {
    // Always make sure result sets and statements are closed,
    // and the connection is returned to the pool
    if (rs != null) {
      try { rs.close(); } catch (SQLException e) { ; }
      rs = null;
    }
    if (stmt != null) {
      try { stmt.close(); } catch (SQLException e) { ; }
      stmt = null;
    }
    if (conn != null) {
      try { conn.close(); } catch (SQLException e) { ; }
      conn = null;
    }
  }
</pre>
</p>

</blockquote></td></tr></table>

</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
        Copyright &copy; 1999-2009, Apache Software Foundation
        </em></font></div></td></tr></table></body></html>